Amiga Format CD 23/Amiga Format AFCD23 (Feb 1998, Issue 107).iso/-coverdisks-/subsdisk/subs.dms/subs/gui4cli.LZX/Gui4Cli/Docs/FastRead.guide

Amigaguide Document | 2003-12-15 | 17KB | 349 lines

@databse HelpSysDoc
@node Introduction
                       FASTREAD.GC DOCUMENTATION
INTRODUCTION
    FastRead.gc is a gui which provides an easy method to access
documentation either completely, in reader mode, or by fetching
selected patches of text for online help from within a Gui4Cli user's
own program.
    This gives the Gui4Cli user an easier and quicker way than
AmigaGuide to write documentation about his program, and the same
document can also be used for quick help from within the user's own
program, although FastRead.gc can also do these things with AmigaGuide
documents as well as its own, just as easily.
    FastRead.gc works in two modes. Firstly it is able to be used as a
document reader, and secondly as quick help from within a program,
fetching and displaying instructions on individual gadgets. It can do
this because it has a separate reader gui, ViewText.g, which displays
the text.  FastRead.gc handles the preprocessing of documents and
displays the index, so is not needed when only online help is
required.  ViewText.g handles this part.
@endnode
@node Requirements
REQUIREMENTS
    The Gui4Cli help system needs no special support libraries or
files, and only needs Gui4Cli installed on the system. The work is
done by two binary files, GetNodes and WriteNode, which are a part of
the Gui4Cli distribution.
@endnode
@node "Where Things Are"
THE FASTREAD DIRECTORY TREE
    Until you are familiar enough with FastRead.gc and its associated
programs to be able to take it and use it for your own purposes, you
may find it helpful to know where things are in relation to your
overall directory structure. You need Gui4Cli to be installed in your
system, and it will use the directory GUIS: as its home base. Within
that environment, FastRead.gc and its friends are located thus :
  GUIS:                      ;Home base for Gui4Cli
    |
    |___Docs                 ;Gui4Cli directory for documents. eg,
    |                        ;HelpSystem.txt (the file you are
    |                        ;reading now), plus any further docs,
    |                        ;guides, etc. which you collect or
    |                        ;create.
    |
    |___C                    ;Gui4Cli directory for binaries. GetNodes
    |                        ;and WriteNode are stored in here.
    |
    |___Tools                ;Gui4Cli directory for global tools, such
          |                  ;as FastRead.
          |
          |___FastRead       ;FastRead.gc, ViewText.g, HelpDemo.gc
                  |          ;and related icons.
                  |
                  |___Idx    ;Directory to hold index files as
                             ;created by FastRead.gc.
@endnode
@node "The GCHELP: Assign"
THE GCHELP: ASSIGN
    For general convenience, the directory name GCHELP: is temporarily
assigned to whatever directory holds FastRead.gc or any of its
associated programs. The assignment is created by the FastRead.gc
suite of programs when any of them start up, and is removed again when
the programs end. The assign will have no effect on anything else you
@endnode
@node "Writing Your Docs"
WRITING A DOCUMENT
    As with AmigaGuide, the doc file is written in any text editor.
The difference is that unlike AmigaGuide, the Gui4Cli help system does
not require the insertion of complex formatting codes. Only three
codes are used - '@node' and '@endnode', to mark the start and end of
various topics that the user wants to access, and a '@database'
header. These are the same markers as AmigaGuide uses. FastRead.gc
will strip out all other AmigaGuide formatting codes when reading
AmigaGuide. Text colours and styles are not supported, since the
handling of AmigaGuides by FastRead.gc is there merely to enable the
user to write his docs in either format and still have access to
online help.
    A document which is intended for access by FastRead.gc needs some
preparatory editing. The file you are now reading has examples of such
editing included. Each section of text which you want to appear in the
index must begin with '@node' and end with '@endnode'. It's as simple
as that. A short title must be placed after '@node'. This is the
subject title which will appear in the FastRead lister.  If the title
contains spaces, enclose it in double quotes. The same applies to the
database title.
    For the purposes of this text, let the | character represent the
extreme left of your editing window. Then the layout of your document
might look like this :
    |@database <title>
    |@node Introduction
    |
    |(Introductory text)
    |
    |@endnode
    |
    |@node "Contacting the author"
    |
    |(Text about the author)
    |
    |@endnode
The first line in a document must be a '@database' statement, and the
last line an endnode statement.
@endnode
@node "The Index File"
THE INDEX FILE
    When your document has been written, and FastRead.gc reads this or
an AmigaGuide file for the first time, an index file will be created
automatically, and stored in the 'GUIS:Tools/FastRead/Lst' drawer.
    The name of the index file will always be the same as the document
it belongs to, with a '.idx' filename extension added. For example, if
your document was called 'MyDoc.guide', the index file would be
created with the name 'MyDoc.guide.idx'.
    The index file is used in the FastRead.gc lister, and it's
contents will look something like this...
Introduction                            38 1047
Requirements                            1114 245
    The numbers are the start and length offsets of the subject text
in bytes, so that FastRead.gc will know where to go to retrieve the
text. These numbers are hidden in the lister, and are used also for
online help within the users program.
@endnode
@node "   Index Format"
FORMATTING THE INDEX
    If your text naturally divides itself into major topics and
subtopics, then subtopics can be indicated by preceding the node
title with, say, three spaces, placed INSIDE the double quotes which
enclose the node title, thus :
    |@node "   Requirements"
The exact number of spaces doesn't matter, but you must be consistent.
    You can indicate sub-subtopics in a similar way. The number of
spaces must be more than the number used for the preceding level, and
should be consistent...
     |@node Introduction
     |(text .. any number of lines)
     |@endnode
     |@node Applications
     |(text)
     |@endnode
     |@node "   Application 1"
     |(text)
     |@endnode
     |@node "      Refinements A"
     |(text)
     |@endnode
     |@node "      Refinements B"
     |(text)
     |@endnode
     |@node "   Application 2"
     |(text)
     |@endnode
     |@node Limitations
     |(text)
     |@endnode
    Note that the subject titles that do not need formatting, and only
consist of one word, have no quotes enclosing them. It would do no
harm to put these node titles in quotes, but would be pointless. The
quotes MUST be there for the other titles in the above example.
@endnode
@node "The Programs"
THE PROGRAMS
    FastRead.gc is the document reader itself, and can work in two
modes. Stand alone, which will read a whole doc file, and Online,
which fetches selected patches of text, or topics from the doc file.
In Stand Alone mode, FastRead.gc does not need the user's program to
be running, and becomes a text file reader. In Online mode, the
commands to fetch text are sent from the user's program instead of
FastRead.gc.
    ViewText.g is the part of FastRead that actually displays the
text, and runs without FastRead.gc for online help, being controlled
from the user's program.
    HelpDemo.gc is a 'mock up' of the user's program, intended to
demonstrate how FastRead.gc is used from within a Gui4Cli script to
obtain online help.
@endnode
@node "   The Binaries"
                             THE BINARIES
GetNode:        Usage: GetNodes <source doc> <.idx file>
    This is the program that creates the index file (.idx) for your
documentation. GetNodes will grab all the node titles in your doc and
calculate the starting byte and length of each one. The .idx file is
laid out like this...
--- Title --------------------------- Start & Length -----
Introduction                            38 1047
Requirements                            1114 245
WriteNode:      Usage: WriteNode <document> <start> <length>
    WriteNode uses the start and length numbers in the .idx file
generated by GetNodes to find and grab the required piece of text from
your document. The piece of text is saved to Ram Disk:, and is always
called 'Guide.txt'.
@endnode
@node "   FastRead.gc"
FASTREAD.GC
    This is the actual text reader. FastRead.gc opens two windows when
in Stand Alone mode, the main window with a lister, containing the
various topics and subtopics of the doc file, and the text window,
which displays the actual text of the topic or subtopic.
    On loading, FastRead.gc presents a file requester from which the
doc file to be read is chosen. After the file has been chosen, the
lister will display the topics and subtopics. A new document can be
loaded at any time via the 'Open' button.
    Clicking with the left mouse button on any topic or subtopic will
bring the text window to the front and display the text. A right mouse
button click brings the lister back to front, and clears the text
window, ready for another topic to be selected. To Quit FastRead.gc,
simply close either of the windows with their close gadget.
    A simple lister search facility is included. This consists of a
string gadget at the top, with a button marked [
] next to it. This
can be useful for very large documents, or for AmigaGuides which
contain hundreds of nodes. By typing any character string into the
string gadget, the first index item which matches will move to the top
of the lister. The search is not case sensitive. For example, the
'Requirements' index item can be found in a long list by typing 'req,
REQ, or reQ' into the string gadget. Clicking on the button marked [
will move the next matching index item to the top of the lister.
    Pressing the HELP key whilst the FastRead.gc lister window is
active will load and display this text. Any document being read at the
time will be kept and not need to be reloaded.
    FastRead understands one icon tooltype - VTMACRO, which sets the
default AmigaDOS or ARexx script to run when the [Macro] button is
pressed in the ViewText window.
@endnode
@node "   ViewText.g"
VIEWTEXT.G
    This is the text window part of FastRead.gc, but is a global file
which can be used by either FastRead.gc or the user's program, and is
used without FastRead.gc for online help. All calls concerning online
help are made from the users program. ViewText.g is initially loaded
from there, and displays the specific text patch requested. See the
section on HelpDemo.gc for more information.
    When the patch of text has been read, a click on the right mouse
button closes ViewText.g. The ViewText.g window has a button strip
along the top to the right, containing four buttons. These are
described as follows...
Macro - Opens a file requester and enables an AmigaDOS or ARexx script
        to be run. If the VTMACRO tooltype is set in FastRead's icon,
        this macro will run without opening the requester.
Prev - This goes to the previous subject in the FastRead.gc lister and
       displays it. When displaying online help, this button is
       ghosted.
Next - This goes to the next subject in the FastRead.gc lister and
       displays it. When displaying online help, this button is
       ghosted.
Grab - Saves the piece of text currently being displayed in the
       ViewText.g listview. A file requester will appear for the save
       path and filename. This function is also accessible by pressing
       CTRL-S.
Quit - This quits completely when used in stand alone mode, for
       reading complete documents. However, in online mode, the Quit
       button simply closes the Viewtext.g window. This function is
       also accessible by pressing CTRL-Q.
@endnode
@node "   HelpDemo.gc"
HELPDEMO.GC
    This is a 'mock up' used to simulate the user's program, and to
demonstrate how to get selected patches of text from the program's doc
file to use as online help.
HelpDemo.gc can be read in any text editor or viewer. (Recommended)
Borrowing parts of HelpDemo.gc for your own project
===================================================
Loading ViewText.g - After 'xOnLoad' are the lines...
    extract fastread.gc guipath fre_path
    assign GCHELP: $fre_path
    delvar fre_path
This grabs the path of HelpDemo.gc and makes a temporary assign. The
full path of ViewText.g is GUIS:Tools/FastRead/ViewText.g, but the
GCHELP: assign is used throughout for convenience. The next important
line is...
      GuiLoad GCHELP:ViewText.g
    This loads ViewText.g without opening its window. Put a copy of
that line in a similar position in your program.
Specify your document - In the script of HelpDemo.gc you will find:
     ; -----  The target document is named here ----
     docname = GUIS:Docs/HelpSystem.txt
    This puts the path and filename of the document into a variable
called 'docname'. Include the same in your program, changing
'GUIS:Docs/HelpSystem.txt' to your document's path and filename.
    Switching help mode on and off is done in this case by a checkbox,
but can be done by almost any gadget you like. Near the top of the
script is the line...
    helpon = 0
which sets the helpmode to off. It will remain off until the checkbox
is selected. The 'helpon' variable is used later to test whether help
has been switched on or off.
Assign topics to gadgets - Find the patch of script which contains
    ; ---- The button for the HelpDemo patch ----
    This is where you will need the '.idx' file which belongs to your
document. The index file is not actually used with online help, but
the byte offset numbers that it contains are used to locate the text
patch in your document. You will see the lines...
    offset = "8639 1992"
    gosub helpdemo.gc open
    The actual numbers are not important here, since they will be the
ones in the .idx file belonging to your document.
    The first line puts the start and length offsets into a variable
called offset. This variable is used later in the script by a
subroutine called 'open', which does the biz. The second of the two
lines jumps to the 'open' subroutine.
    At the bottom of the HelpDemo.gc script you will see the
subroutine as follows...
; ---------- This is the routine for opening the reader gui...
    xroutine open
    if $helpon = 0
        return
    elseif $helpon = 1
        cli 'GUIS:C/WriteNode $docname $offset'
        guiopen viewtext.g
        guiwindow viewtext.g front
        lvuse viewtext.g 1
        lvchange ram:guide.txt
        stop
    endif
This subroutine is shared by all the gadgets that use online help. To
go through it line by line...
    if $helpon = 0
        return
    If the helpmode has not yet been activated, go back to the routine
of the gadget that called the 'open' subroutine and carry out any
commands remaining there.
    elseif $helpon = 1
        cli 'GUIS:C/WriteNode $docname $offset'
    Alternatively, if the helpmode has been activated, run the
WriteNode binary in GUIS:C, and send to it the document path and
filename, and the offset (start and length) numbers.
    WriteNode will grab the required text from the document, and
create a file in the Ram Disk: called 'Guide.txt' which contains the
text. See the section on the binaries for more information.
      1  guiopen viewtext.g
      2  guiwindow viewtext.g front
      3  lvuse viewtext.g 1
      4  lvchange ram:guide.txt
      5  stop
1 - Open the reader window. 2 - Bring it to the front. 3 - Select its
listview as the current one. 4 - Import the file 'Ram Disk:Guide.txt'
into the listview and display it. 5 - Halt all operation and wait for
the user. Read the HelpDemo.gc script for more information.
@endnode
@node "Rogues' Gallery"
AUTHORS
    The Gui4Cli Help System was written as a joint project between
Graham Maddox of the UK and John Collett of New Zealand.
Graham Maddox - The concept and all Gui4Cli scripts.
<[e-mail]>
John Collett - Document format concept and most of the development.
<[e-mail]>
Dimitris C. Keletsekis - Kindly supplied the binary engines.
<[e-mail]>
@endnode